# Sprint 3: Bandas, Canais e Osciladores (Donchian, Keltner, Price Channel, KDJ)

Este plano abrange a implementação de 4 novos indicadores, combinando overlays baseados em volatilidade/canais e o oscilador KDJ para apresentar na UI. O objetivo é manter o altíssimo padrão de arquitetura visual e matemática (O(N) batch, O(1) incremental) definidos nos Sprints 1 e 2.

## User Review Required

> [!IMPORTANT]  
> Por favor, revise as fórmulas sugeridas e os períodos padrão abaixo. Confirme se as regras de cálculo para **Price Channel** (se diferem de Donchian) e a fórmula do **KDJ** estão de acordo com o padrão esperado pelo TradingView.

## Indicadores Propostos e Especificações

### 1. Donchian Channels (Overlay)
- **Descrição**: Capta a volatilidade observando os extremos (Highest High e Lowest Low) do preço.
- **Fórmula**:
  - `Upper = Max(High, N períodos)`
  - `Lower = Min(Low, N períodos)`
  - `Middle = (Upper + Lower) / 2`
- **Período Padrão**: 20
- **UI**: 3 Linhas Overlay + Preenchimento (opcional/translúcido) entre Bandas.

### 2. Keltner Channels (Overlay)
- **Descrição**: Bandas de volatilidade centradas em uma média móvel exponencial (EMA), expandidas pelo ATR.
- **Fórmula**:
  - `Middle = EMA(Close, N)`
  - `Upper = Middle + (Multiplier * ATR(N))`
  - `Lower = Middle - (Multiplier * ATR(N))`
- **Períodos Padrão**: N = 20, Multiplicador = 2.0
- **UI**: 3 Linhas Overlay + Preenchimento translúcido.

### 3. Price Channel (Overlay)
- **Descrição**: Muito semelhante ao Donchian, mas muitas vezes avaliado ignorando a barra atual ou variando a lógica de offset.
- **Fórmula Proposta**:
  - `Upper = Max(High, N períodos anteriores)` (ou incluir o atual, favor confirmar)
  - `Lower = Min(Low, N períodos anteriores)`
- **Período Padrão**: 20
- **Open Question**: Como você prefere diferenciar a engine do Price Channel em relação ao Donchian Channel?

### 4. KDJ (Panel)
- **Descrição**: Oscilador clássico muito utilizado no mercado financeiro global, derivado do Stochastic.
- **Fórmula**:
  - `RSV = ((Close - MinLow(N)) / (MaxHigh(N) - MinLow(N))) * 100`
  - `K = SMA(RSV, K_Period)`
  - `D = SMA(K, D_Period)`
  - `J = 3*K - 2*D`
- **Períodos Padrão**: N=9, K_Period=3, D_Period=3
- **UI**: Panel Indicator (nova área desenhada abaixo do gráfico principal), desenhando curvas K, D e J.

---

## Proposed Changes

### Domain Models (`lib/src/domain/models/indicators/`)
- `donchian_value.dart` / `donchian_indicator.dart` (Freezed)
- `keltner_value.dart` / `keltner_indicator.dart` (Freezed)
- `price_channel_value.dart` / `price_channel_indicator.dart` (Freezed)
- `kdj_value.dart` / `kdj_indicator.dart` (Freezed)

### Calculators (`lib/src/engine/indicators/`)
- `donchian_calculator.dart`
- `keltner_calculator.dart`
- `price_channel_calculator.dart`
- `kdj_calculator.dart`

### Painters (`lib/src/presentation/painters/indicators/`)
- `donchian_overlay_painter.dart`
- `keltner_overlay_painter.dart`
- `price_channel_overlay_painter.dart`
- `kdj_panel_painter.dart`

### Providers & UI (`lib/src/presentation/providers/` & `ChartWidget`)
- Criar providers (`donchian_providers.dart`, etc.)
- Inserir no pipeline principal de `ChartWidget`
- Adicionar checkboxes de testagem no `example/lib/main.dart` com paletas de cores únicas.

---

## Open Questions

> [!WARNING]  
> 1. Diferenciação Matemática: Qual fator deve diferenciar o **Price Channel** do **Donchian Channel** em nossa implementação? 
> 2. KDJ: Deseja aplicar algum `smoothing` especial para K e D, ou a média móvel simples (SMA de Wilders) é suficiente?

Aguardando sua aprovação para iniciarmos a geração de classes e codificação da arquitetura!
